Back to Contents Previous Next
7. Saving data with ‘save windows’ **
Easy facilities are provided for adding and controlling ‘save windows’ - which are traditionally used to save data to files on a hard or floppy disc etc. The following user-functions are all involved in a strict, but simple, procedure:
FNuser_savefiletype
FNuser_savedata
PROCuser_saveicon
Copy the file “Template4” from the Tutorials folder (Tutor1 sub-directory) into !MyApp and rename as “Templates”. Load in the ‘save’ window:
save%=FNwimp_loadwindow(“<MyApp$Dir>.Templates”,“save”,0)
and after PROCwimp_attachsubmenu(mainmenu%,3,i3menu%)
, add:
PROCwimp_attachsubmenu(mainmenu%,5,save%)
If you run !MyApp now, a standard ‘save window’ will duly open when you move across item 5 of mainmenu%
. But nothing else will happen because we haven’t yet given it any code to tell it what to do.
Things starts to work when you change FNuser_savefiletype
as follows:
DEF FNuser_savefiletype(window%)
return$=””
IF window%=save% THEN return$=“FFF”
=return$
This is the first step: DrWimp now knows that save%
is a save window and that it saves text files. Don't try it just yet as DrWimp will try to filetype the saved file and it is not created, so will throw up an error.
For the next step we move to FNuser_savedata
. Whenever the file icon in a save window (i.e. one that has been identified by FNuser_savefiletype
in the above way) is dragged to a destination (or the OK button clicked after entering a full save path) FNuser_savedata
is automatically called by Dr Wimp - with, as usual, all the parameters filled with the current ‘live’ values. So, path$
will hold the full pathname of the file-plus-window that you are saving to (the ‘destination’ file) and window%
will hold the handle of the window that the icon was dragged from (the ‘source’ file).
Thus, it is in FNuser_savedata
that you add your required saving actions and an example of this follows.
Firstly, you will notice that FNuser_savedata
contains the following unusual lines:
LOCAL ERROR
ON ERROR LOCAL =2
These lines allow DrWimp to respond if an attempt is made to save to a protected floppy disc or a locked hard drive. It is suggested that they be REMed out until your saving code works properly so that errors are reported to you. Any local variables should be declared before these lines, and the rest of your saving code after them.
So, enter the following into FNuser_savedata
, after the local error lines:
return%=0
IF window%=save% THEN
file%=OPENOUT(path$)
BPUT#file%,“This is a text file,”
BPUT#file%,“created by MyApp.”
CLOSE#file%
PROCwimp_menuclose
return%=1
ENDIF
and replace the last line of the DEF FN
with:
=return%
Remember: the filetyping is taken care of by DrWimp as a result of the FNuser_savefiletype
action earlier.
A vital point is to note that FNuser_savedata
returns a number. This is 0 by default, but can be 1 (or a 2 if a local error occurs). In our tutorial listing above we have changed the return to 1 when we use the function. It is very important that you do this when you use this user-function in this way - and return the default value of 0 in other cases. This ensures that the Wimp knows you have taken saving action and it will complete the Wimp saving protocol correctly and do the file-typing.
You can now Run !MyApp, open the save window from the main menu and then drag the file icon to any filer window (or click the OK button, after typing a complete path in the writable icon) and a new textfile containing the above text will be created. The standard error messages like “You must drag the icon to a filer window to save...” etc. are taken care of by DrWimp.
We have not yet introduced PROCuser_saveicon
. To make things work automatically behind the scenes - which includes handling both dragging the file icon or clicking the OK button - Dr Wimp needs to know the icon numbers of the three key icons in any save window. That is, the (draggable) file icon, the writable icon and the OK button. Dr Wimp calls these drag%
, write%
and ok%
respectively.
If you examine the tutorial’s save window in a template editor (!WinEd, for instance) you will see that:
Icon 0 is the (draggable) file icon, called drag%
Icon 1 is the writable icon, where the filename or pathname goes, called write%
Icon 2 is the OK button, to click on to save to the pathname, called ok%
These are regarded as the default values - but you may want to use different numbers for these icons in your application. This is where PROCuser_saveicon
comes into play.
If you are using a save window with different values (e.g. drag%=3
, write%=15
, ok%=1
) then you must tell Dr Wimp by adding something like the following line to PROCuser_saveicon
:
IF window%=save% THEN drag%=3:write%=15:ok%=1
Thus, you simply set these icon numbers to whatever you have used in your window template and this action overrides the default values.
Note that PROCuser_saveicon
is a little different from most PROCs in that - by using the RETURN
keyword (plus a space) in front of each of the three variables drag%
, write%
and ok%
- it works rather like a FN
, because it then returns to Dr Wimp the new values of these parameters. But whereas a FN
can only return one value, RETURN
allows a PROC
to return as many values as you wish.
As you can see, the ‘save window’ procedure is not difficult but must be followed strictly. (If the ‘Save box’ file icon will not drag or nothing happens when the drag finishes, the chances are that you have not used all three of the above ‘saving user-functions’ correctly.)
The parameter values in FNuser_savedata
allow you to do some checking before deciding whether to save or not. For example, at the start of FNuser_savedata
, you could check to see whether the file path$
exists. If it does then use FNwimp_errorchoice
to allow the user to decide whether to overwrite the file or not.
You can have as many save windows as you wish. Simply load them in, add them to a menu (or provide some way the user can get to them), return their filetype from FNuser_savefiletype
, and do the saving in FNuser_savedata
.
If the data you wish to save is already in the form of a file loaded into a memory block then you can use in FNuser_savedata
one of the file-saving wimp-functions introduced later - see Sections 2.12 and 2.13.
Remember also that you can open a window - including a ‘save window’ - from a menu. If you add the following to the bottom of PROCuser_menuselection
:
IF menu%=mainmenu% AND item%=5 THEN
PROCwimp_menupopup(save%,3,0,0)
ENDIF
Now select the save item from the save menu. You will see that the save window opens near the mouse pointer and stays open until you complete the save or click elsewhere i.e. the window behaves like a menu - as you might expect in this case.
[Your !RunImage listing should now look like listing RI_05 in Tutor1
(apart from the REM
lines, perhaps). Do not destroy it as the tutorial picks up again in the Section 2.9 where it continues from this stage.]
Saving a directory/application
All the above procedures are aimed specifically at saving files rather than saving a directory or an application. However, it is not difficult to modify the file-saving arrangements to do this. Indeed the !Fabricate utility - authored with Dr Wimp - does this.
The important point to note is that you must always ensure that FNuser_savefiletype()
returns a valid file-type string for the ‘save window’ you are using - even though the file-type will only be used as a dummy and even though you will have probably changed the ‘save window’ drag icon to show a directory/application sprite. (”FFF” is a good file-type string choice, but anything in the range “000” to “FFF” will do.) Without this precaution dragging will not start.
After this, the necessary coding can mainly be confined to DEF FNuser_savedata()
where - early in your routine - you need to create the new directory directly, using PROCwimp_createdirectory()
. You can then add coding to create/copy other files/directories into the new directory as required, making sure they are file-typed if you are creating any new files.
Finally, it is safest to ensure that DEF FNuser_savedata()
returns 1 after this process.
Saving to an application rather than a directory uses the same procedure but some extra steps are normally required. There will be a need to create/copy appropriate !Boot
and !Run
files - and also to ensure that an application sprite is created, correctly named (with the usual lower-case version of the application name) and placed in the new application in the usual !Sprites
/!Sprite22
files. It is far easier to create all these extra files outside the programme, ready to copy them into the new application.
If you need any assistance concerning saving to a directory/application please do not hesitate to contact the Dr Wimp author.
Top of page Back to Contents Previous Next